Skip to content

feat: Card MD3 Expressive improvements - #5116

Open
pawelkata wants to merge 51 commits into
callstack:mainfrom
pawelkata:expressive-card
Open

pawelkata wants to merge 51 commits into
callstack:mainfrom
pawelkata:expressive-card

Conversation

@pawelkata

@pawelkata pawelkata commented Sep 11, 2026 •

Copy link
Copy Markdown

Motivation

Card still followed the Paper 5 model, so it was hard to build a Card that matches Material 3:

  • Layout depended on arbitrary children. Spacing and corners came from inspecting what was nested inside the Card, so a Card's look changed with the order of its children.
  • The Material 3 visuals were incomplete. There was no hover or pressed state layer on web, the outline used the wrong color role, and a disabled Card looked enabled.
  • The interaction model was unclear. A Card with onPress could also hold buttons, which gives screen readers and keyboards two competing targets.

This PR moves Card to the Material 3 contract: a variant prop, explicit slots, one actionable target, and the state layers, elevation and focus ring from the Material 3 Card spec.

- <Card mode="contained" onPress={open}>
-   <Card.Cover source={cover} />
-   <Card.Title title="Title" subtitle="Subtitle" />
-   <Card.Content><Text>Body</Text></Card.Content>
- </Card>
+ <Card
+   variant="filled"
+   onPress={open}
+   media={<Card.Cover source={cover} />}
+   title="Title"
+   subtitle="Subtitle"
+   content={<Card.Content><Text>Body</Text></Card.Content>}
+ />

Breaking changes are listed, with before and after code, in the Card section of the migration guide:

  • mode is replaced by variant (filled, elevated, outlined), and the default is now filled.
  • Children are replaced by the media, header (or title, subtitle, leading, trailing), content and actions slots.
  • A Card with an interaction handler is a single button, and giving it actions as well logs a development warning. A Card without a handler is a neutral container.
  • Card.Actions no longer sets the mode of its buttons.
  • The outline color moves from style.borderColor to the borderColor prop.
  • Card.Cover styles the image itself, and aspectRatio sizes it responsively.
  • Each region pads its own top and sides with 16dp, and the Card adds 16dp below its last region. Card.Content used outside a Card has no bottom padding, and Card.Title has no minimum height.

Related issue

Addresses #4929.

Screenshots / Videos

All before shots are from main and all after shots from this branch, using the same comparison screen with the same content.

Variants and slots (web). Every Card keeps the height and spacing it has on main. All 8 cases match to the pixel in height and text position. The visible differences are the Material 3 changes:

  • the filled container uses surfaceContainerHighest;
  • the outlined border uses outlineVariant;
  • the disabled Card is dimmed to 38%;
  • action rows sit 16dp from the sides, as the spec's left/right padding requires.
image

Interaction states (web). main shows no hover or pressed feedback. This PR adds the Material state layer, 8% on hover and 10% when pressed or focused, and keeps the outward focus ring.

image

Android and iOS. Same layout as main. Covers keep main's rounded corners on every side, as in the Material 3 card examples.

image image

The broken back arrow and the icon font toast in the main phone shots come from my local main checkout, which couldn't load the icon font. They are not part of the Card change.

Pressed on Android. The foreground ripple covers the whole Card, media included.

image

Performance

Layers that draw nothing are no longer mounted:

  • Container layer: drawn only when a disabled Card has to fade its container.
  • State layer: drawn only on actionable or dragged Cards.

I counted the views each Card mounts, and timed mounting 200 Cards in Jest (median of 15 runs). The times only show the direction of the change, not real device speed.

Card Views per Card Mount 200 Cards
Neutral, filled or elevated 6 → 4 −9 to −11%
Neutral, outlined 7 → 5 −8%
Actionable, filled 6 → 5 −3%
Actionable, outlined 7 → 6 −1%
Disabled unchanged unchanged

Hover, focus and press change only the Card's own state, so slot content isn't re-rendered (does not rerender stable memoized slot content for transient feedback). Card is not wrapped in React.memo: slot elements are usually written inline, so they are new on every parent render and the memo check would always fail.

Test plan

In the example app, open Card and switch between filled, elevated and outlined with the chips at the top.

  1. Web:
    • Hover Pressable Chameleon. A tint should cover the whole Card, image included.
    • Press Tab until the Card is focused. The ring should sit outside the Card's edge, and an outlined Card's border should turn darker while focused.
  2. Android: press and hold a pressable Card. The ripple should cover the whole Card, image included.
  3. iOS: press and hold a pressable Card. The pressed tint should appear.
  4. States and customization section:
    • Disabled should be dimmed and not focusable.
    • Dragged should show its tint and the higher elevation.
    • Custom outline color should keep its color at rest.
  5. Screen reader: a pressable Card should be announced as one button with its label. A Card with actions should keep each action as its own control.
  6. Dark mode: turn on Dark Theme in the drawer and check that the container, outline and state colors switch.


type CardVariantProps = FilledCardProps | ElevatedCardProps | OutlinedCardProps;

export type Props = Omit<ViewProps, 'children' | 'style'> &

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#5076 drops React.Children using context but keeps <Card><Card.Content/></Card>. I'm afraid moving every region to a prop goes further than #4954 asks for - could Card take that route instead?

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kept the slots on purpose. The task behind this PR (#4929) lists "clearer slot-based APIs" in its acceptance criteria, and Dialog has since moved to the same pattern in #5072 (title, content and actions props). The slots also give a fixed region order and let Card treat media, header and actions differently, without a layout context. If we'd rather keep children for Card, I think that's a decision for both Card and Dialog together.

Comment thread src/components/Card/Card.tsx Resolved
Comment thread src/components/Card/tokens.ts Resolved
Comment thread docs/plugins/component-docs/parser.ts Outdated
const type =
(hasUnionDeclarations && new Set(declarationTypes).size > 1) ||
!declarations.includes(property)
new Set(declarationTypes).size > 1 || !declarations.includes(property)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This changes prop types on every component page. Have you checked the others?

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, it did. I ran main's parser and this one on all 65 pages: 16 prop types on 11 other pages had become long intersection types, for example IconButton.onPress and List.Item.style. Fixed in b0a89b7. The parser merges types again only when every declaration is a union branch, now also counting type aliases a file uses as union members, and it skips never branches. Only the Card page differs from main now, and a regression test covers IconButton.onPress and Appbar.Content.title.

Comment thread src/components/Card/CardActions.tsx Resolved
@JKobrynski

Copy link
Copy Markdown
Collaborator

And we've got conflicts

@satya164

satya164 commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Review by Claude

iOS

  1. Pressed feedback is applied twice. Steps: dark app theme, press and hold the "Filled (default)" Card. What happens: the container goes from gray value 51 to 86 (0 to 255 scale) in one frame. One 10% onSurface layer gives about 68. The TouchableRipple underlay (stateLayerPressed, 10% onSurface) and the Card's own pressed state layer (10% onSurface) both draw. What should happen: one pressed layer at 10%. (via Claude, verify if it makes sense)
  2. State layer changes do not animate. Steps: record the screen at 60 fps and press and release the same Card. What happens: the pressed layer appears and disappears in one frame on press in and on press out. What should happen: a fade over short3 (150 ms) with the standard easing, as the PR describes. (via Claude, verify if it makes sense)

Android

  1. A disabled Card looks enabled. Steps: open the "States, shapes, and omitted slots" section. What happens: the "Disabled action" Card keeps full-contrast title and body text. Only the outline is fainter, so it reads the same as an enabled outlined Card. What should happen: the content is dimmed to the disabled opacity (0.38), like Compose CardDefaults does with disabledContentColor. (via Claude, verify if it makes sense)

Android, light theme: disabled outlined Card keeps full-contrast text

Web

  1. The hover state layer does not cover the media. Steps: hover the "Filled (default)" Card. What happens: the area under the cover image darkens by the 8% hover layer, but the image pixels do not change at all. The state layer is drawn below the slot content, so media hides it. The same applies to focus and dragged layers. What should happen: the state layer covers the whole Card, image included. (via Claude, verify if it makes sense)

Web, light theme: rest (left) and hover (right). Only the area below the image changes.

(via Claude, verify if it makes sense)

@satya164 satya164 left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review by Claude

Points without a diff line:

  1. The branch conflicts with main. #5076 landed and changed Card.tsx, CardActions.tsx, CardContent.tsx, CardCover.tsx, utils.tsx, the Card tests and CardExample.tsx. The open thread on Card.tsx line 178 about slots versus children needs an answer before the rebase, because main now has the context-based children API.
  2. The Card.Content padding change is a visible migration change that the guide does not mention. In v5 the padding depended on neighbors. Now it is always 16 on all sides, so Card.Content followed by Card.Actions gets 24 between the text and the buttons. (via Claude, verify if it makes sense)

Comment thread src/components/Card/Card.tsx Outdated
contentStyle,
theme: themeOverrides,
testID,
testID = 'card',

@satya164 satya164 Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The default testID is still here. The reply on the earlier thread says it was removed, but only the derived -container and -visual IDs went away. #5099 removed default test IDs because they collide. On the example screen, 5 neutral Cards expose the identifier card on iOS and the resource-id card on Android, so getByTestId('card') and E2E selectors match several nodes. The tests in Card.test.tsx that use getByTestId('card') need an explicit testID after this change.

Suggested change
testID = 'card',
testID,

(via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed during the rebase (ae5f64a). Card has no default testID now, and the tests pass explicit IDs.

Comment thread src/components/Card/Card.tsx Outdated
Comment on lines 533 to 561
const stateLayerAnimatedStyle = useAnimatedStyle(
() => ({
opacity: currentInteractiveVisuals.value.stateLayerOpacity,
transitionDuration,
transitionProperty: ['opacity'],
}),
[currentInteractiveVisuals, transitionDuration]
);
const outlineAnimatedStyle = useAnimatedStyle(() => {
const outlineColor = currentInteractiveVisuals.value.outlineColor;

const total = React.Children.count(children);
const siblings = React.Children.map(children, (child) =>
React.isValidElement(child) && child.type
? typeof child.type !== 'string' && 'displayName' in child.type
? child.type.displayName
: null
: null
return {
borderColor: outlineColor,
opacity: currentInteractiveVisuals.value.outlineOpacity,
transitionDuration,
transitionProperty:
typeof outlineColor === 'string'
? ['borderColor', 'opacity']
: ['opacity'],
};
}, [currentInteractiveVisuals, transitionDuration]);
const focusIndicatorAnimatedStyle = useAnimatedStyle(
() => ({
opacity: disabledState.value ? 0 : focused.value ? 1 : 0,
transitionDuration,
transitionProperty: ['opacity'],
}),
[disabledState, transitionDuration]
);

@satya164 satya164 Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These worklets return transitionDuration and transitionProperty, but Reanimated CSS transitions run when React commits new style props. A value that a worklet writes on the UI thread does not start one. I recorded the iOS simulator at 60 fps while pressing the filled Card: the pressed layer appears and disappears in a single frame on press in and press out. So short3, the standard easing, theme.animation.scale and reduced motion have no visible effect on the state layer, the outline and the focus indicator. AnimatedElevationSurface in Surface.tsx has the same shape, so elevation changes also jump.

Since these are changes between fixed states, use React state with Reanimated CSS transitions instead. The comment on line 487 shows how.

The snapshot tests do not catch this because they only assert the style objects. (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right, and the old snapshots showed it too: the hover snapshot recorded opacity: 0 and elevation: 0 on a hovered card, because the values never reached the rendered tree. Fixed in 204f1da with React state, as you suggested on line 487. Measured on web, the state layer now fades 0 → 0.08 in about 150 ms with the standard easing and fades back out the same way.

Comment thread src/components/Card/Card.tsx Outdated
Comment on lines +811 to +816
<TouchableRipple
{...actionableAccessibilityProps}
ref={touchableRef}
testID={testID}
borderless={false}
hoverColor="transparent"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pressed feedback is drawn twice. TouchableRipple adds its own pressed feedback (the underlay on iOS, the ripple on Android, both stateLayerPressed, which is onSurface at 10%), and the Card state layer adds another 10% onSurface for pressed. On the iOS simulator in the dark theme, the filled Card goes from gray value 51 to 86 while pressed. One 10% layer gives about 68.

hoverColor="transparent" already handles this for hover on web. For press, let one of the two own it. Keeping the ripple is closer to Material on Android, so set the Card pressed state layer opacity to 0 and keep the pressed elevation and outline tokens. The other option is rippleColor and underlayColor set to transparent, which removes the Android ripple. (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 239701d. I kept the ripple, as you suggested. Card skips its own pressed state layer, and the pressed elevation and outline tokens still apply. The token matrix keeps the spec's 10% so Card.tokens.test.ts still matches the spec; Card just doesn't draw it because the ripple does.

Comment on lines +798 to +809
<Animated.View
pointerEvents="none"
style={[
StyleSheet.absoluteFill,
shapeStyle,
{
backgroundColor: visuals.stateLayerColor,
},
stateLayerTransitionStyle,
stateLayerAnimatedStyle,
]}
/>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The state layer renders before the slot content, so media paints over it. On web, hovering the "Filled (default)" Card darkens only the area below the cover. The image pixels do not change at all. Focus and dragged layers have the same problem. Material draws state layers over the whole component, so render this Animated.View after the content (it already has pointerEvents="none").

Web, light theme: rest (left) and hover (right) (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in ebf337e. The state layer now renders after the slot content, so hover, focus and dragged feedback also tint the cover image. It already had pointerEvents="none"

Comment on lines 638 to +641
const content = (
<View style={[styles.innerContainer, contentStyle]}>
{React.Children.map(children, (child, index) =>
React.isValidElement(child)
? React.cloneElement(child as React.ReactElement<any>, {
index,
total,
siblings,
})
: child
)}
<View
style={[styles.content, contentStyle]}
testID={hasPassedTouchHandler ? undefined : testID}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A disabled Card dims only its container or outline. The title, subtitle and content keep full contrast, so the disabled outlined Card on the example screen looks the same as an enabled one with a fainter border. Compose CardDefaults.cardColors, elevatedCardColors and outlinedCardColors set disabledContentColor to the content color at 38%. Apply the disabled opacity to this content wrapper when isDisabled is true, or at least to the header that Card renders from title and subtitle.

Android, light theme: disabled outlined Card keeps full-contrast text (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in adfd6e0. resolveCardVisuals now returns contentOpacity (0.38 when disabled, like Compose's disabledContentColor), and Card applies it to the slot content wrapper. This also dims media in a disabled Card, which I think is the right look for a disabled state. A test checks it directly.

Comment on lines +14 to +20
jest.mock('react', () => jest.requireActual('../../../../node_modules/react'));
jest.mock('react-native-reanimated', () =>
jest.requireActual('../../../../node_modules/react-native-reanimated')
);
jest.mock('react-native-paper', () =>
jest.requireActual('../../../../src/index')
);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This suite fails to run in a clean checkout:

Cannot find module 'react-native-paper' from 'example/src/Examples/__tests__/CardRenderCountExample.test.tsx'

yarn test ends with 1 failed suite (57 suites, not the 58 in the PR description). jest.mock resolves the module name before it uses the factory, and nothing maps react-native-paper at the repo root. The manual mocks of react and react-native-reanimated by relative path also work around the example workspace resolution. Card.test.tsx already has "does not rerender stable memoized slot content for transient feedback", which checks the same behavior through the public API. Remove this file, or move any extra case into Card.test.tsx. (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed, together with the example (19ec680). Card.test.tsx still has the memoized slot content test.

Comment thread docs/6.x/docs/guides/migration.md Outdated

Paper 6 warns in development if whole-Card interaction handlers and a populated `actions` slot are combined. A neutral Card remains a grouping container unless you provide accessibility semantics explicitly. The `dragged` prop controls the Material dragged presentation only; drag gestures and lifecycle remain application responsibilities.

Card refs and test IDs now target documented nodes: `ref` targets the outer shell, `touchableRef` targets the actionable interaction node, and `testID` targets the interaction node for actionable Cards or the slot-content node for neutral Cards. `${testID}-container` and `${testID}-visual` identify the outer shell and clipped visual region.

@satya164 satya164 Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

efe5d34 removed the derived IDs, so the last sentence describes IDs that Card no longer renders.

Suggested change
Card refs and test IDs now target documented nodes: `ref` targets the outer shell, `touchableRef` targets the actionable interaction node, and `testID` targets the interaction node for actionable Cards or the slot-content node for neutral Cards. `${testID}-container` and `${testID}-visual` identify the outer shell and clipped visual region.
Card refs and test IDs now target documented nodes: `ref` targets the outer shell, `touchableRef` targets the actionable interaction node, and `testID` targets the interaction node for actionable Cards or the slot-content node for neutral Cards.

(via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied your suggestion (dbca050).

title={title}
content={
<Card.Content>
<Text variant="titleLarge">{title}</Text>

@satya164 satya164 Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Card now gets title={title}, so this line renders the title a second time inside the content.

Suggested change
<Text variant="titleLarge">{title}</Text>

(via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed (06895c1).

Comment on lines 39 to 44
// styles are guarded with a snapshot of the rendered tree instead.
const expectVisualSnapshot = () => {
expect(screen.toJSON()).toMatchSnapshot();
};

afterEach(() => {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Most visual tests assert through this helper, which produces an 11,612-line snapshot file. The test rules ask to avoid assertions on exact internal style values, and a snapshot of the whole tree is that, at a size nobody can review. It also needed the jest/expect-expect change in eslint.config.mjs. The token matrix already has direct tests in Card.tokens.test.ts. Keep a few small snapshots for the variants and assert behavior (roles, disabled state, callbacks) for the rest. (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 71bdb83. One small snapshot per variant is left, and the snapshot file went from about 9.8k lines to 530. The other tests reach the layers through a small helper from the Card's testID and compare their styles with resolveCardVisuals. The jest/expect-expect override is reverted. As a check, forcing the state layer opacity to 0 makes 14 tests fail.

Comment thread example/src/Examples/CardExample.tsx Outdated
Comment on lines +275 to +298
<View
style={[
styles.verification,
{ borderColor: theme.colors.outlineVariant },
]}
>
<Text variant="titleMedium">Platform verification</Text>
<Text variant="bodySmall">
Android · iOS · web: compare layout, both themes, surface roles,
outlines, clipping, and elevation.
</Text>
<Text variant="bodySmall">
Web: use Tab and hover on actionable Cards to inspect focus and state
layers.
</Text>
<Text variant="bodySmall">
Native: touch actionable Cards to inspect bounded ripple, clipping,
and elevation. Current platform: {Platform.OS}.
</Text>
</View>

<View style={styles.section}>
<CardRenderCountExample />
</View>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example app ships to the app stores now (#5118). The "Platform verification" block gives review instructions ("use Tab and hover ... to inspect focus and state layers"), and CardRenderCountExample is a render-count benchmark. Both are QA tools, not Card demos. Move them out of the gallery. The previous example also had a variant switcher and covered more layouts, such as a cover with only actions and custom button styles. (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rebuilt in e8bebf4 and 970b8d9. The QA blocks are gone, including the light/dark comparison panels. The variant switcher is back, along with main's layouts on the slot API: a cover with only actions, custom button styles, a custom corner radius, long press and theme switching. A states section shows disabled, dragged, custom elevation, a custom outline colour, an asymmetric shape, a horizontal layout and a custom header. Every Card that can follows the switcher. The cover-with-actions card couldn't at first because of a typing issue with header-less Cards, which is now fixed (3ea4bfa).

@satya164 satya164 left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review by Claude

See the inline comments. (via Claude, verify if it makes sense)

Comment thread src/components/Card/Card.tsx Outdated
Comment on lines +483 to +487
const disabledState = useSharedValue(isDisabled);
const draggedState = useSharedValue(dragged);
const hovered = useSharedValue(false);
const focused = useSharedValue(false);
const pressed = useSharedValue(false);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hover, focus, press, drag and disabled are changes between fixed states. Nothing here follows a gesture or a scroll position. So these fit Reanimated CSS transitions with React state, as in Checkbox and Badge on main, better than shared values. This replaces the earlier suggestion to call withTiming inside the worklets.

Keep hovered, focused and pressed in useState, pick the visuals during render, and pass plain styles:

const [pressed, setPressed] = React.useState(false);

const current = isDisabled
  ? disabledVisuals
  : dragged
    ? draggedVisuals
    : pressed
      ? pressedVisuals
      : focused
        ? focusedVisuals
        : hovered
          ? hoveredVisuals
          : enabledVisuals;

<Animated.View
  style={[
    styles.stateLayer,
    {
      opacity: current.stateLayerOpacity,
      transitionProperty: 'opacity',
      transitionDuration,
      transitionTimingFunction,
    },
  ]}
/>

The transitions then start when React commits the new style, disabled and dragged need no effect to copy them, and the shared values and useDerivedValue go away. The cost is one Card render per state change. (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 204f1da. Hover, focus and press are in useState, and resolveCardVisuals runs once during render with all the flags. The state layer and outline get plain styles with CSS transitions, and the shared values, useDerivedValue and useAnimatedStyle are gone.

Comment thread src/components/Surface.tsx Outdated
* A Reanimated shared value can drive elevation without a React render.
*/
elevation?: Elevation;
elevation?: Elevation | SharedValue<Elevation>;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With React state in Card, Card can pass a plain elevation here. Surface on main already runs background, elevation and shadow changes through CSS transitions, so a state change in Card animates with no extra code. An elevation change on hover or press is a state transition, not gesture or scroll driven motion, so it does not need a shared value. Please drop SharedValue<Elevation> and AnimatedElevationSurface. That path also skips the CSS transitions, as the comment on Card.tsx notes. (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped in 204f1da. Surface.tsx and its test are identical to main again, and Card passes a plain elevation. That also broke the StaticSurface entry in the docs config, which I fixed in 768913d.

Comment thread src/components/Card/CardCover.tsx Outdated
borderRadiusStyles,
});
const CardCover = ({ style, theme: _theme, ...rest }: Props) => {
const usesAspectRatio = StyleSheet.flatten(style)?.aspectRatio !== undefined;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This flattens the whole style prop on every render to read one value, and the layout now depends on what the style happens to contain. A dedicated prop states the intent and needs no StyleSheet.flatten:

const CardCover = ({ aspectRatio, style, theme: _theme, ...rest }: Props) => (
  <Image
    {...rest}
    style={[
      styles.image,
      aspectRatio === undefined ? styles.defaultHeight : { aspectRatio },
      style,
    ]}
    accessibilityIgnoresInvertColors
  />
);

The prop docs, the usage example and the migration guide would then use aspectRatio={16 / 9}. (via Claude, verify if it makes sense)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in c9f72d4 with your suggested aspectRatio prop. While testing it in the app, I found that an image from a static require() source keeps its own pixel height, which wins over the ratio: a 16:9 cover was 510px tall instead of 272. So Card.Cover also sets height: 'auto' together with aspectRatio (681d419). The docs and the example use aspectRatio={16 / 9}.

@Doberjohn Doberjohn added this to the 6.0.0 milestone Oct 30, 2026
@Doberjohn Doberjohn added the needs pickup Work that has been started but needs someone to pick it up and continue. label Nov 5, 2026
@Doberjohn Doberjohn removed the needs pickup Work that has been started but needs someone to pick it up and continue. label Nov 9, 2026
@Doberjohn Doberjohn modified the milestones: 6.0.0, 6.0.0-beta.0 Nov 12, 2026
@Doberjohn Doberjohn assigned Stoneski93 and unassigned alpharius-ck Nov 16, 2026
@Doberjohn

Copy link
Copy Markdown
Collaborator

/review

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 3 new findings on 19ec680. The verdict and the full list are in the summary comment.

Comment thread docs/6.x/docs/guides/migration.md Resolved
Comment thread docs/6.x/docs/guides/migration.md Resolved
Comment thread src/components/Card/Card.tsx Resolved
@Stoneski93

Copy link
Copy Markdown
Collaborator

Dialog takes actions: ReactNode[] and lays the buttons out itself. Card keeps actions: ReactNode with Card.Actions for the usual button row, because the MD3 Card guidelines allow chips, sliders, links and several action areas there, not just a row of buttons. Are we OK with the two components differing here?

Paweł Kata and others added 8 commits November 18, 2026 16:34
BREAKING CHANGE: Card.Content now always applies fixed padding, and Card.Actions no longer assigns button modes or child margins.
BREAKING CHANGE: Card now accepts media, header, content, and actions slots; arbitrary children composition and the mode prop are removed.
@Doberjohn

Copy link
Copy Markdown
Collaborator

/review

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 2 new findings on 9f244d2. The verdict and the full list are in the summary comment.

Comment thread src/components/Card/Card.tsx Outdated
Comment on lines +461 to +471
const [hovered, setHovered] = React.useState(false);
const [focused, setFocused] = React.useState(false);
const [pressed, setPressed] = React.useState(false);

React.useEffect(() => {
if (isDisabled) {
setHovered(false);
setFocused(false);
setPressed(false);
}
}, [isDisabled]);

@apex-sentinel-staging apex-sentinel-staging Bot Nov 18, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No longer raised on 48772be: marked fixed in 7d5d214 by Stoneski93 in this comment.

🆕 🟡 Minor · Hover state sticks when a Card unmounts its interaction node

Hover a Card whose only handler is onPressIn/onPressOut, then rerender it with onPress={undefined} or disabled: the interaction node unmounts so handleHoverOut never runs, and when it remounts enabled hovered is still true showing the 8% state layer with the pointer long gone. Only isDisabled clears the three state flags (effect at line 465); nothing clears them when the handler that made the Card actionable disappears.

Suggested change

Clear hovered/focused/pressed whenever hasPassedTouchHandler goes false, not only when the Card is disabled.

Details

persona: javascript, senior-developer

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if it is wrong — I will re-check the cited code.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/like

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the feedback. It helps us make these findings more useful.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 7d5d214. Hover, focus and press now reset when the Card loses its touch handler, not only when it's disabled. A test hovers a Card, removes and restores onPressIn, and checks that the state layer is back to 0.

Comment on lines +654 to +662
const handleFocus: NonNullable<TouchableRippleProps['onFocus']> =
React.useCallback(
(event) => {
focusTarget.onFocus?.(event);
setFocused(isKeyboardFocusEvent(event));
onFocus?.(event);
},
[focusTarget, onFocus]
);

@apex-sentinel-staging apex-sentinel-staging Bot Nov 18, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No longer raised on 48772be: marked fixed in 48772be by Stoneski93 in this comment; the code it pointed at changed.

🆕 🟡 Minor · Descendant focus lights the Card's keyboard-focus state layer

Focusing a focusable descendant (e.g. TextInput) of an actionable Card lights the Card's keyboard-focus state layer: native focus events bubble, so handleFocus runs and setFocused(isKeyboardFocusEvent(event)) executes unconditionally—isKeyboardFocusEvent returns true for every native event. The shared ring hook below guards this with e.target !== e.currentTarget, but Card bypasses that guard for its own focused state.

Suggested change

Only call setFocused when event.target === event.currentTarget (or reuse a guarded helper), so a focused descendant does not put the Card into its Material focused presentation.

Details

persona: senior-developer

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if it is wrong — I will re-check the cited code.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/like

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the feedback. It helps us make these findings more useful.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 48772be. Card's own focused state now ignores focus that bubbles up from a descendant, using the same event.target === event.currentTarget check as useFocusRing. A test fires a bubbled focus event and checks that the state layer stays at 0

@Doberjohn

Copy link
Copy Markdown
Collaborator

Dialog takes actions: ReactNode[] and lays the buttons out itself. Card keeps actions: ReactNode with Card.Actions for the usual button row, because the MD3 Card guidelines allow chips, sliders, links and several action areas there, not just a row of buttons. Are we OK with the two components differing here?

Yes, keep actions: ReactNode with a public Card.Actions. A Card’s action area can hold chips, sliders or links, so it shouldn’t force an array. Dialog can widen its actions to ReactNode later without breaking anyone, so the two can line up then.

Without a touch handler the interaction node unmounts and sends no hover
out or blur, so a Card that became actionable again showed the hover state
layer with the pointer long gone.
Native focus events bubble, so focusing a TextInput inside an actionable
Card lit the Card's focused state layer. Only the interaction node's own
focus counts now, as in useFocusRing.
@Doberjohn

Copy link
Copy Markdown
Collaborator

/review

@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of 48772be

Since the review of 9f244d2: 3 new · 0 still open · 2 no longer raised (2 marked fixed)

3 finding(s): 3 minor.

🟡 Minor (3)

Where Finding
src/components/Card/Card.tsx:495 🆕 onHoverIn/onHoverOut without a press handler are ignored: no hover state layer either
src/components/Card/tokens.ts:292 🆕 Custom resting elevation is dropped the moment a Card is hovered or focused
src/components/Card/Card.tsx:495 🆕 A Card with only onHoverIn/onHoverOut is a focusable button with no press action
Not in the reviewers' prompt (1 file)
  • src/components/__tests__/Card/__snapshots__/Card.test.tsx.snap: generated or a lockfile, so its lines were left out

Reviewed with this repository's own Sentinel configuration (677ab9f2b2cf).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 3 new findings on 48772be. The verdict and the full list are in the summary comment.

Comment on lines 495 to 497
const hasPassedTouchHandler = hasTouchHandler({
onPress,
onLongPress,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🆕 🟡 Minor · onHoverIn/onHoverOut without a press handler are ignored: no hover state layer either

A Card with only onHoverIn/onHoverOut and no press handler takes the neutral branch because hasTouchHandler checks only the four press handlers, so TouchableRipple is never mounted and the hover state layer never lights.

Suggested change

Either include onHoverIn/onHoverOut in the hasTouchHandler check, or document that a press handler is required for hover feedback to work.

Details

persona: senior-developer, javascript

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if it is wrong — I will re-check the cited code.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is intentional. In Material 3, only actionable Cards have hover, focus and pressed states. A hover layer on a Card that does nothing on click would suggest it's clickable. The prop docs already say these callbacks are for an actionable Card, and main doesn't handle hover-only Cards either.

Comment thread src/components/Card/tokens.ts Outdated
Comment on lines +292 to +295
elevation:
variant === 'elevated' && state === 'enabled' && customElevation != null
? customElevation
: stateTokens.elevation,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🆕 🟡 Minor · Custom resting elevation is dropped the moment a Card is hovered or focused

<Card variant="elevated" elevation={5}> drops to elevation 2 on hover and 1 on focus, returning to 5 only when hover ends. resolveCardVisuals applies customElevation only when state === 'enabled', so any transient state replaces the consumer's value with the token-matrix constant. Hover/focus should keep the custom resting value (or the token delta on top), as Chip does—the restriction that only enabled elevated Cards accept the prop is already enforced by the type.

Details

persona: senior-developer, javascript

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if it is wrong — I will re-check the cited code.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This follows the spec. The MD3 tokens give each state of an elevated Card a fixed elevation (hover level 2, focus and pressed level 1, dragged level 4), and elevation is documented as the resting value. Compose does the same: in CardDefaults.elevatedCardElevation(), changing defaultElevation doesn't change hoveredElevation. main also used 2 when pressed, whatever elevation was set. Chip has no custom elevation, so it isn't a comparable case.

Comment on lines 495 to 497
const hasPassedTouchHandler = hasTouchHandler({
onPress,
onLongPress,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🆕 🟡 Minor · A Card with only onHoverIn/onHoverOut is a focusable button with no press action

<Card onHoverIn={fn} content={...} /> gets role/aria-role 'button' and tab-stop focusability via TouchableRipple's isControl, but hasTouchHandler ignores onHoverIn/onHoverOut so no press handler is wired—Enter, Space, and taps do nothing.

Suggested change

Either treat onHoverIn/onHoverOut as presentation-only (keep the Card neutral, drop the role/focusability) or document that hover callbacks alone make the Card an inert button target.

Details

persona: react-native-paper

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if it is wrong — I will re-check the cited code.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@apex-sentinel-staging dislike Without a press handler, Card renders a plain View, not TouchableRipple (see the neutral branch of the render). So it gets no button role and no tab stop. The other finding on this line says the same: TouchableRipple is never mounted.

The Card.Cover rewrite brought back the 195 that main had replaced with
194 in callstack#5076, a leftover of the rebase rather than a decision. 194 is the
16:9 media height of a 344dp Material card (344 x 9/16, rounded), and the
Material 3 spec sets no cover height, so main's value stays.
A custom borderColor replaced the outline color in every state, so an
outlined Card with one showed no outline change on keyboard focus.
Material 3 turns the outline onSurface on focus, the only state where its
color changes, so the custom color now gives way there.
Card.Cover no longer wraps its image in a View, so its style is typed as
ImageStyle and lands on the Image. The migration guide shows how to style
the area around a cover instead.
The test looked the Button up by testID because the actionable Card is
also a button and took its name from the Button's text. Giving the Card
its own label keeps the accessibility query unambiguous.
`isDisabled || ariaDisabled` reads as redundant but keeps an enabled
neutral Card from rendering aria-disabled={false}, and React.Children in
the actions check only keeps an empty slot from triggering the warning.
tokens.ts now holds only the Material token data, as in Switch, Checkbox
and FAB, and the resolver that turns it into visuals for a theme and state
lives in utils.ts. The token table is exported as CardTokens, after
SwitchTokens and CheckboxTokens.
Card.Title, Card.Content and Card.Actions used bare numbers. They now read
one CardSpacing group in tokens.ts, which says where each value comes
from: the 16dp left/right padding is the Material 3 spec, and the
Card.Title heights are kept from Paper 5, since the spec sets none. No
value changes.
Every Card token was compared with the live md.comp.*-card values on
m3.material.io on 2026-11-20 and all of them still match. The earlier
AndroidX references stay, with their own date.
Two of the Card's full-size layers were invisible in most states:

- The container layer painted the same opaque color as the visual node
  behind it. Only a disabled filled or elevated Card needs it, to fade the
  container but not the content, so it is drawn only then.
- A neutral Card has no hover, focus or press, so its state layer stayed
  at 0% unless the app set `dragged`. It is drawn only for an actionable
  or dragged Card, so a neutral Card's dragged tint now appears and clears
  without a fade.

Views per Card: neutral 6 to 4 (outlined 7 to 5), actionable 6 to 5
(outlined 7 to 6); disabled unchanged.

The rendering matches the previous one apart from anti-aliasing on the
rounded corners, in screenshots of every variant:

- web: at rest, hovered, pressed and keyboard-focused;
- iOS simulator: at rest, and pressed through `testOnly_pressed`;
- Android emulator: at rest, and during a real held touch, where the
  foreground ripple still covers the whole Card, media included.
The rebase brought back Paper 5's Card.Title heights (72 and 50 minimum,
30 and 20 per line), which main removed in callstack#5076, and Card.Content's
bottom padding stacked with Card.Actions' top padding. A full Card was
20px taller than on main, with no reason in the Material 3 spec, which
sets only the 16dp left/right padding.

Each region now pads its own top and sides with 16dp, and the Card adds
16dp below a last header or content region, chosen from the populated
slots alone. An action row ends 8dp below its buttons. Card.Title sizes
from its content and spaces its parts with a 16dp gap, so a trailing
element also sits 16dp from the edge.

All eight cases of the comparison screen now match main to the pixel in
height and text position. A row layout removes the closing space with
`contentStyle={{ paddingBottom: 0 }}`, as the example and the migration
guide now show.

BREAKING CHANGE: Card.Content used outside a Card no longer has bottom
padding, and Card.Title has no minimum height.
The Card.Cover rewrite dropped the cover's own corner radius and relied
on the Card's clipping alone, so a cover met the rest of the Card with
square corners. The Material 3 card examples round the image on every
side, the inner corners included, and Paper 5 and main round it with
`corner.medium`.

Card.Cover again rounds all four corners with the theme's
`corner.medium`, which also puts its `theme` prop back to use. The Card
still clips its media to its own shape, and `style.borderRadius` still
replaces the rounding.
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Found potential problems with the pull request:

  • The description is too long. Please keep it under 1000 characters.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants